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PREFACE 


3UG/65 i 3 an interactive debugging tool for use in 
the development of assembly language programs for the ATARI 
800 or ATARI 400 personal computers. It's designed to take 
as much of the drudgery out of assembly * language debugging 
as possible. The design philosophy behind BUG/65 is that 
the computer should serve as a tool in the debugging process 
as opposed to a hindrance. One result of this philosophy is 
that BUG/65 requires a relatively large amount of memory 
when compared to simpler debug monitors. This is the result 
of a tradeoff between memory and functionality, with 

function winning out. 

BUG/65 is a RAM loaded machine language program 
occupying 8K of memory; it is self relocatable as shipped 
and requires a full 4GK bytes of memory. BUG/65 is also 
designed to be floppy disk based — it isn't intended to be 
used in cas 30 tte-only systems. BUG/65 was designed for use 
by an experienced assembly language programmer. 

BUG/65 is an original product of the McStuff 
Company, which developed the product under the name "McBUG**, 
which name is their trademark. 


For use on the ATARI 800 or 400 computer with a 
minimum of 48K of RAM and one floppy disk drive. 


TRADEMARKS 


The following trademarked names are used in various 
places within this manual, and credit is hereby given: 

OS/A+, BlJG/65, MAC/65, and C/b5 are trademarks of 

Optimized Systems Software, Inc. 

Apple, Apple II, and Apple Computer(s) are trademarks 

of Apple Computer, Inc., Cupertino, CA 

Atari, Atari 400, Atari 800, Atari Home Computers, and 

Atari 050 Interface Module are trademarks of 
Atari, Inc., Sunnyvale, CA. 







SUMMARY OF MAJOR FEATURES OF BUG/65 


A full 


sot of debugging commands - change memory, 
display memory, goto user program with break 

point s, etc. 


* Binary file read and write, including 

write. 


appended 


A disassembler. 

An instant assembler providing labeling capability. 

Expanded command addressing capability* hex or 

decimal addresses, ♦ and - operators 
supported, relocated addresses supported. 


Read or write disk sector(s). 

Multiple commands permitted in a command 

Command lines can be repeated with a 
keystroke or repeated forever with 
special slash operator. 


1 ine. 
ingle 
the 


Support for relocatable assemblers - the base of a 

module can be specified and then used to 
reference addresses in that module. 


BUG/65 commands can be executed 

and there is a command 
files . 


from a command file, 
to create command 


Hex 


to decimal 
provided 


and decimal to hex conversions 


Memory 


Pago 


y protection of BUG/65's code and data. BUG/65 
won't allow you to use a BUG/65 command that 
will destroy any part of BUG/65 itself. For 
example, you can’t use the Fill command to 
overwrite BUG/65's code. 

zero sharing. BUG/65 shares page zero with a 
user program by keeping two copies of the 
shared page zero locations - one for the user 
and one for BUG/65 itself. 






SUCTION 1 : 


COMMAND SUMMARY 


This section is intended to he u handy reference 
9 uide and will probably prove indispensable after the user 
has thoroughly read through the rest of this manual. For 
the experienced debug user, might we suggest at least a 
quick perusal of Sections 2 through 6 and Sections 8 and 9. 

The following table is simply a syntax summary of 
the available commands. Excepting for the first three 
commands (which are described in Section 8) # all the 
commands are described in alphabetical order in Section 7. 


COMMAND 

CODE SYNTAX PURPOSE 


(RETURN} 

/ 


Repeat last comman1 line 

When appended to a command 
line: repeat line forever. 

Display last command line 


A A <addr>)6 Ascii mode memory change 

B D <addr> Base address for relocation 

C C <startaddrl> <endadlrl> <startaddr2> 

Compare memory blocks 

D D <startaddr> [<endaddr>] Display memory 

E E Ifilespec Execute a command file 

y y <startaddr> <endaddr> [<value>] 

Fill memory block with value 

G G [ < sta rt addr > ] [ £ < brea'/.po in t > [ Rn=* < value> ] [I=<count>] ] 

Go at address, set optional 

breakpoint, with optional Register 

value breakpoint and pass Counter. 

p H < number1> <number2> Hexadecimal arithmetic result 

j I disk Inventory (directory listing) 

j J •fileapec,string create command file 

K K <number> convert hex to decimal 


L <startaddr> <endaddr> <bytel> [<byteN> ...] 

Locate byte string in memory block 

M <startaddr> <endaddr> <toaddr> 

Move memory block 

P [S] [P] Print output on Screen and/or 

Printer 

q Quit...go to OS/A+ 

R [<offset>] Ifilespec Read a binary file to memory 

with optional offset 

R% [<sectornumber> [<bufferaddr> [<numsectori>] ] ] 

Read sector(s) from disk to 
memory buffer 

S <addr>)6 Substitute memory, numeric mode 

T [S] [<count>] Trace, with optional Skip over 

subroutine calls, for (optional) 
count intstructions. 

U <addr> [<param>] ca1L User routine at given 

address and pass optional 
parameter in X,Y registers 

V View user registers 

W [:A] <startaddr> <endaddr> Ifilespec 

Write a block of memory to a 
binary image file, optionally 
appending instead of creating 
new file. 

Wl [<sectornumber> [<bufferaddr> [<numsectors> ] ] ] 

Write sectors from memory 
buffer to disk 

XA or XX or XY or XS or XP or XF 

change user register value 

Y <startaldr> [<endaddr>] 

dissasemble memory block 

Z <addr>)6 instant assembler (at address) 







SECTION 2: Notations Used In This Manual 


The following notations are used in this manuals 

<...> Is used to indicate a numerical address parameter. 

The address expression between the two 
characters and »>“ may be any valid 

address as described in Section 3. For 
example, <START> means that you can enter any 
valid address expression to specify the START 
parameter. 

b Is used to indicate one and only one blank. In 

most cases, blanks are insignificant and any 
number of them may be entered between 
commands and parameters. However, in certain 
cases, one and only one blank must be entered 
- this blank is indicated by the "P 

character. 

f 3 Is used to specify an optional parameter. For 

example, [<VALUE>] would indicate that VALUE 
is an optional address parameter. You'll find 
that many parameters are optional, and in 
such cases logical default values will be 
supplied by BUG/65. 

or IS used to delimit a list of choices. In such a 

list, one and only one choice may be used. 
For example, “♦ or indicates that you may 
enter a plus sign or a minus sign, but not 
both . 

filespec Is used to indicate a standard OS/A. files,»ec. 

This consists of the device name followed by 
a colon and the filename. For example. 
“0:DATAFILE" is a valid filespec for a file 
named DATAFILE on disk drive one. 
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SECT101) 3: Address Parameters 


3IIG/6S allows numerical addresses to be specified 
in a variety of ways. You can use hexadecimal or decimal 
notation, add and subtract terms, or add a relocation factor 
to any address. The following Backus-Naur definitions 
describe the various address types: 


<ADDR> 

:* 

♦ or - <TEKM> 

[ . or - <ADDR > ] 

<TERM> 


<14UMBER> or 

% 

X <tiUMUER> 

‘NUMBER. 

:- 

‘DECNUM. or 

<HEXNUM> 

OECNUM > 

• a 

.‘DECIMAL DIGITS. 

<HEXNUM> 


‘HEXADECIMAL 

DIGITS. 


In the above, the only item not literally defined 
is the “X" item in the definition of a TERM. This is used to 
indicate that the following NUMBER is to bo relocated by 
adding the value of the current relocation base to the value 
of UUHBER. The current relocation base is set by the “B* 
command. 

All address parameters are interpreted as 16-bit 
positive numbers in the range of 3 to 65535. Overflow isn't 
detected or reported as an error. 

Some examples will help (all of these are valid 
address expressions): 

1FA1 a hexadecimal number. 

.100 a decimal number (one hundred). 

1000..20 a hexadecimal number plus a decimal 

number. This evaluates to 1014 hex 
(4116 decima 1 ). 

1+2-3.4 a long expression. Evaluates to 4. 

a relocated address. If the current 
relocation ba3e has the value 
$1000, then this expression will 
evaluate to $2234. 


XI 234 





3.1 Spaces as Pjrancuc Delimiters 


DUG/o5 uses spaces as parameter .lelimiters. This 
makes for easier an.l quicker entry of commands. However, it 
Hoes introduce some conventions regarding the use of spaces 
that you must be aware of: 

* Spaces may not be embedded in a number. For example, 

“12 34" is interpreted as two parameters ($12 
and $34) and not as the single parameter 
$1234. 

* Spaces aren't allowed between the "X" relocation 

specifier and it's associated relocated 
address. For example, “X 1234” is interpreted 
as two parameters. The first will have the 
value of the current relocation base and the 
second is S1234. 

* Any number of spaces may be used to separate two 

parameters. For example, “1234 5678" is 
a perfectly valid way of entering the two 
parameters $1234 and $5678. 


--G-- 



SECTIOtl 4: Loading and Running BUG/65 


3UG/65 Is shipped on your master diskette as a 
relocatable COMmand file, named “BUG65.COM". Therefore, 
BUG/65 functions just as does any 0S/A+ extrinsic command: 
simply type “BUG65“ when OS/At prompts with Dl: (or Dn: if 
you have changed default drives...see the 0S/A+ manual for 
more details) and BUG/65 will load into memory and relocate 
itself to just above the current value of LOMEM (contents of 
$2E7-$2E8). 

4.1 Specifying UUG/65's Load Address 


If you need BUG/65 to load at some location other 
than LOMEM (which is typically around $2000 with OS/At 
version 2 and around $2C00 with version 4), you may also 
enter a load address on the 0S/A+ command line. The address 
must be in hex, must be at or below $9AQ0, and should be 
above LOMEM. Remember, BUG/65 occupies 8K bytes, which 
means it will occupy memory starting at the address you give 
and ending $2000 bytes higher. 

EXAMPLE: ” .; 

(Dl:]BUG65 8000 4 

This usage will load BUG/65 at $6000, set its 
restart point at $8200, and occupy memory from 
$8000 through $9FFF. 












4.2 Creating a Won-Relocatable Version 

In order to allow itself to be relocated virtually 
anywhere in memory, BUG/65 as shipped includes a relocation 
bit map and a relocation program. In addition, repeatable 
BUG/65 always loads in at locations $9800 through $BC(30. If 
these addresses are “poison" to you (e.g., if you want to 
use BUG/b5 with a cartridge plugged in), you may wish to 
produce a non-relocatable version designed to run within an 

address range you pick. 

If so, USING A 48K SYSTEM, simpLy specify the 
lortjpoint, as shown in the preceding section (e.g, via 
-BUG65 7000") and alLow BUG/65 to load and relocate. Then 
exit to OS/A*- (via Quit) and use the OS/A+ intrinsic comman 
SAVE to save a non-relocatable version. The address range 
to be SAVEd may be calculated as follows: 

SAVE filename.COM loadpoint♦$200 loadpoint+$2000 

Thus, if you had speefied "BUG65 7000". you could save the 
non-relocatable version via 

SAVE BUG700O.COM 7200 9000 

thus also giving it a name which will later remind you where 
it will load at. To execute this non-relocatable version, 
simply type in its name (BUG7000 in the example shown). 


SECTION 5: Command Entry 


When you see BUG/65's input prompt (the “>" 
character) in the left-hand column of the screen. ►hen 
you're in command entry mode. Any data typed at that point 
will be entered into the command line buffer - the command 
line isn t executed until you type RETURN. You can enter as 

many commands in one command line as will fit in the command 

line buffer (1J0 characters). As soon *as you type the 

RETURN, you'll leave command entry mode and BUG/6‘3 will 
begin executing the command(s) in the command line. 

You can tell the difference between command entry 

mode and command execution mode. In command entry mode, the 

cursor is lisplayed. When a command is executing, the cursor 
is blanked. 

rf you try to enter more than 100 characters in 

the command line, BUC/65 will beep the bell and not allow 

any more characters to be input. At that point, you may 

either hit RETURN to execute what's in the command line so 

far, or edit some characters out of the command line with 
the BACKSPACE key. 

5.1 Command Line Editing 


When entering commands, you may edit mistakes with 

the BACKSPACE key. The BACKSPACE will move the cursor one 

column to the left and delete whatever character was in that 

column. Unfortunately, the normal system editing facilities 

aren t supported. This is because of the manner in which 
BUG/65 does keyboard input. 
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5.2 Normal and Immediate Type Commands 


DUG/65 has two types of commands - normal and 
immediate. Normal commands are those that 5on t require 
interaction with the operator for their execution. Immediate 
commands do require operator interaction. Normally# you 11 
never be aware of the distinction between the two types 
command entry "flows" without any consideration of the 
command type required. The only difference is that an 
immediate command must be the first command entered in a 
command line. Once an immediate command is entered, DUG/65 
will begin interacting with the operator for further input. 
Since this interaction is required for completion of the 
command, it doesn't make sense to allow immediate commands 
to be "stacked" in the middle of a command line for 
execution between other commands. If you try to enter an 
immediate command in the middle of a command line, you 11 
get an "IMMEDIATE ERROR" error message and find yourself 

back in the command entry mode. 


The immediate 
memory change), the "S" 
command (change user 
(instant assembler). 


commands are 
command (hex 
reu i sters), 


the "A" command 
memory change), 
and the "2" 


(ASCI T 
the "X" 
command 


5.3 Command Execution 


For a normal type command, QUG/65 will begin 
command execution as soon as you type RETURN. For immediate 
type commands. BUG/65 will begin command execution as soon 
as you type the command character (provided that character 
is the first character in the command line). 


— Id — 
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5.4 Multifile Commands on a Line 




Multiple commands may be entered on the same 
command line. Normally, successive commands in the command 
line don't require command separators between them other 
than at least one space character. The exceptions to this 
are commands for which an optional parameter is being 
defaulted. For example, the display memory command ("D") may 
have an optional parameter specified as the end of the area 
of menory to be displayed. If that ending parameter isn't 
specified, BUG/65 will default the end to the start plus 
eight bytes. If you wanted to enter two succeeeive display 
commands in the command line without defaulting the end 
parameters, you could type 

D 1000 1010 D 2000 2010 



and no command separators would be required because BUG/65 
knows that the "U” command only has two parameters and will 
interpret further characters in the command line as the 
beginning of a new command. However, if you wanted to 
default the ending address of the first display command, 
then you'd have to insert a command separator so that BUG/65 
knows that the first display command is finished. If you 
didn't do this, then the second display command "D" would be 
interpreted as the second parameter of the first display 
command (the end address would be interpreted as $0D. The 
command separator is a comma, so in this case you would 
enter the commands as follows; 

D 1000, D 2000 2010 



4 







SUCTION 6: Command Termination 



This section describes the many ways that a 
command will stop. 

6.1 Normal Termination 


Once a command line is given to BUG/b r > for 
execution, DUG/65 will execute all of the commands in the 
line to conclusion before returning to command entry mode. 
It's possible to instruct DUG/65 to execute a command line 
"forever" (see Section 0.2), in which case niJG/i> r > will never 
come back to command entry mode until you manually intervene 
(with r.SC or BREAK - see Section 6.1) 


6.2 Krror Termination 


If an error occurs i r» command execution, DUG/bS 
will beep the bell and display a short error message in 
English indicating the cause of the error. Command execution 
will stop and you'll enter the command entry mode. Any 

commands in the command line after the command which caused 
the error won't be executed. (You should also be awar* that 
BUG/65 will close any file that has been opened using lOi.'U 
number one when any error occurs.) (A complete list of 
error messages is in Section 14.) 

6.3 Command Suspension 


Once UUG/65 begins executing a command 1ine, you 
may temporarily suspend command execution by hitt iug the 
space bar. This will put DUG/b r > in a "hold" condition, it 
which point you have two a 1 tern.i t i ves: you can restart the 
command by hitting the space bar again, or you can abort the 
command with ESC or BREAK. 

6.4 Command Abort 


You can abort any command that is executing 
(except for the read and write disk commands) by hitting the 
KSC or BREAK keys. UUG/6 r > will stop executing the command 
and you'll enter command entry mode. 



e 
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6.5 The RESET Key 


BUG/65 traps the RESET key bo that hitting RESET 
will bring you back to BUG/65. RESET will stop any command 
that is executing. You'll see the BUG/65 version and 
copyright prompt, and you'll be in command entry mode. RESET 
will reset all of BUG/65*s internal stuff except for any 
user defined or modified parameter#. For example, the 
user's registers, the current relocation base, etc., aren't 
cleared on a RESET - they'll retain whatever value# they had 
before the RESET. (All of this depends, however, on the 
fact that the reset vectors haven't been modified by the 
user - either by using a BUG/65 command or by a user 

program. If you've modified the reset vectors, then the 
action of the RESET key is your responsibility.) 

6.6 Manual Restart 


Since BUG/65 is relocatable, the manual restart 
point (coldstart) depends upon where it has been relocated 
to. If you specified an address to load BUG/65 when you 
gave the QS/A+ command line (e.g., BUG65 4000), then the 
coldstart point is $200 greater than the address specified, 
and you may use 'RUN address' from OS/A + if desired (e.g, 
RUN 4200 if the original command was BUG65 4000). In any 
case, you may inspect location $000C (via the BUG/65 command 
'D C') to determine the coldstart point. The 6502 word 
address in locations $0C and $0D (LSD, MSB order) points to 
BUG/65's restart point. The result of a manual restart is 
the same as if the default RESET key processing occurred 
(see section 6.5). 


--1 3-- 
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SECTION 7: Command Descriptions 


Throughout the descriptions of the commands, 
comments are sometimes presented in the command line 
examples. These are denoted by the characters Anything 
appearing on a line after these characters is a comment and 
is NOT part of the command line being exemplified. 


The commands are presented in alphabetical order. 


7.1 A - Change Memory, ASCII mode 


A <ADDR>)6 

The A command allows you to replace the contents of 
memory bytes beginning at location <ADDR> with ASCII characters. 

As soon as you type the required space character after the 
address, BUG/65 will prompt you with the current contents of the 
memory location at <ADDR>. Those, contents will be displayed as 
an ASCII character. At that point, you have the following 
options: 

1. Typing a SPACE will cause the current memory 

location to be skipped and the contents of 
the next memory location to be displayed. 

2. Typing an UNDERLINE will cause the current address 

to be decremented by one. The new address is 
then displayed on the next line of the screen 
foLlowed by the contents of the new memory 
location. 

$ 

3. Typing a RETURN will cause the address of the 

current memory location to be displayed on 
the next line of the screen followed by the 
contents of the current location. 

4. Typing ESC will get you out of the command and back 

into command entry mode. 

5. Typing any character other than will cause the 

ATASCII value of that character to be entered 
into memory at the current address. The 
address is then incremented by one and the 
contents of the new memory location are 
displayed. 

6. Typing the character causes the next character 

typed to be entered into the current memory 
location as its pure ATASCII value without 
any of its control character significance. 

For example, typing ESC" will insert the 
ATASCII value for ESC into memory. The 
address is then incremented by one and 
operation continues as in 5. above. 

After you exercise any option except option 4., BUG/65 
will again prompt you with the contents of the current location 
and you may then choose from any option again. 
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7.2 B - Set Relocation Baae 


B <ADDR> 

The B command will set the value of the relocation 
ba3e to ADDR. The relocation base is intended for use with 
relocating assemblers. In a relocatable environment, listings 
typically are addressed from location zero. When a module to be 
debugged is subsequently loaded into memory, it will have a 
relocation offset added to the addresses in the listing. The B 
command allows you to set the relocation base to the load 
address of the module you're working on and then to reference 
addresses within the module by simply prefixing each address 
expression with the relocator symbol *'X". 

For example, suppose that a relocatable module is 
loaded at location $5380 in memory. Suppose further that we 
want to display the contents of a memory location which is $230 
from the beginning of the module. The following commands would 
do the job; 

B 5380, D X230 

The world isn't overrun with relocating assemblers for 
the ATARI. However, until it is, the B command has other useful 
app1ications. These take advantage of the fact that the 
relocation base value is a variable which can be modified during 
command execution. For example, suppose you know that the 
string of characters "ALICD" is stored somewhere on a diskette 
and you want to find the sector that contains it. The following 
commands will do the trick; 

B 1 

D X, R% X 400(3 1, L 4000 407F 41 42 43 44, B X + l/ 








* 


This uses some commands not introduced yet, but this 
is what happens: First, X is sot to 1 with one command line. 
Then a second command line will display memory at the location X 
(so you'll know where you’re at as you step through), read 
sector number X into memory locations $4000-$407F, locate the 
string "AQCD" in that sector buffer, then bump X by one for the 
next sector. The slash at the end of the command line means 
that the command line will execute forever. What will happen is 
that BUG/65 will continuously read diskette sectors. For every 
sector read, you'll see at least a memory display of eight bytes 
beginning at address X (which is the sector number). If the 
Locate instruction finds the string "ABCD" in the sector buffer, 
it will display the location of the string. At that point, just 
hit ESC to stop the command, and display the value of X ("D X 
RETURN"). The sector containing the string will'-either be the 
value of X or one before it, depending on how fast your ESC was. 

7.3 C - Compare Memory Blocks 


C <STARTBL0CK1> < ENDBL0CK1> <STARTBLOCK2 > 

Compare is used to compare the contents of two blocks 
of memory. The block of memory beginning at STARTBLOCK1 and 
ending with ENDBLOCK1 is compared to the same size block 
beginning at STARTBLOCK2. If both blocks are the same, then 
there will be no output. If any bytes in the blocks differ, 
then BUG/65 will display a line of data in the following format 
for every byte that is different; 

AAAA » BB CCCC * DD 

where AAAA * the hex address of the differing location 
in the first block, BB » the hex contents of location AAAA, CCCC 
“ the hex address of the differing location in the second block, 
and DD » the hex contents of location CCCC. 
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7.4 


D - Display Memory 


D <START> [ <END> ] 

The D command displays the contents of the memory 
block beginning at START and ending at END. If END isn't 
specified, then the default value of START4-7 is used. The 
memory block is displayed in the following formats 

AAAA - BB BB BB BB BB BB BB BB CCCCCCCC 

where AAAA =* the hex address of the first byte in this 

line, BB » the hex contents of successive memory locations 

beginning at location AAAA, and C = the ASCII character 

interpretation of the positionally corresponding BB value of the 
byte . 

7.5 E - Execute a Command File 


E #filespec 

The E command is used to execute a command line from a 
command file. The file specified by filespec must consist of a 
line of BUG/65 commands and parameters and must be ended with an 
ATASCI I EOL character (§90). BUG/65 will only execute one 
command line from a command file and then it will stop reading 
the file. Command files can be chained however, so that the 
last command in one file can execute another command file. An E 
command should be the last command in a command lino because any 
commands after the E in the line won't be executed. 

7.6 F - Fill a Memory Block with a Value 


F <START > < END > [ <VALUE> ] 

The F command will fill the block of memory beginning 

with START and ending with END with VALUE. If VALUE isn't 

specified, then zero will be used. Note that VALUE is a byte 

value - the least significant byte of the 16-bit VALUE will be 
used for the fill. 


t 
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7.7 G - Goto a User Program 


G [<START>] [ @ < BRKPOI NT > [ RN= <VALUE > ] [l=*<COUMT>] ] 

The G command will execute a user program beginning at 
START. If START isn't specified, then execution begins at the 
current value of the user's PC register. BRKPOINT is an 
optional breakpoint. If the user's program trys to execute the 
instruction at BRKPOINT, the program will break back to BUG/65 
and BUG/65 will display the contents of the user’s registers at 
that point. Examples: 

G 1000 /* go at location §1000, no breakpoint 

G @4300 /* go from wherever our PC was and break 

/* at location §4300 

A breakpoint may be conditionally qualified by a 
required value in a specified register. “RN*<VALUE>" will tell 
BUG/65 to break at that point only if the value of user register 
"N" equals VALUE. If that condition isn't met, then the user's 
program is allowed to continue executing at the location of the 
breakpoint. (The instruction that was at the breakpoint 
location WILL be executed.) The mnemonic names of the registers 
that may be specified for M N" are: A, X, Y, S, and P, which 
stand for the user's A, X, Y, Stack, and Status (flags) 
registers respectively. (Note that only the least significant 
byte of VALUE is used for this qualification.) 

Example: 

G 1000 @1422 RX=33 /* go from location §1000 and 

/* break at location §1422 
/* only if register X equals 
. /* $33 

A breakpoint may also be qualified with an iteration 
counter. M I»<COUNT>" tells BUG/65 to allow the execution of the 
instruction at the breakpoint COUNT times before breaking. 

i 

Example: 

G 1000 @2300 1-2 /* go from location §1000 and 

/* break the second time we hit 
/* the instruction at §2300 
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The register and iteration qualifications may be used 
together. In this case, the register condition must be met 
before the iteration counter is decremented. As in the 
following example: 

G 1000 @1234 RA-50 1*3 /• go from location $1000 

/* and break the third time 

/* the instruction at loc- 

/* ation $1234 is executed 

/• with register A equal 

/* to $50 

All of this flexibility isn't without its price, 

however. Because BUG/65 has to do quite a bit of evaluation at 
every breakpoint before deciding if the break condition has been 
met, don't expect to be able to conditionally pass through 
breakpoint instructions at real-time speed. As long as you 
never execute the instruction at the breakpoint, you’re OK, but 
as soon as BUG/65 gets the break, expect several hundred 
instructions to be executed before your program is given back 
control after the break isn't met. 

Also, BUG/65 was NOT designed to allow breakpoints in 
PROM resident code. If you attempt to set such a break point, 
or if you try to set a breakpoint at a non-existent memory 

location, you'll get a "BREAKPOI NT ERROR". 

One other thing. BUG/65 will automatically remove 

breakpoints from your program after a break occurs. Breakpoints 

aren't left set after the break is performed. 

7.8 11 - Hexadecimal Arithmetic 


II <NUMBER 1 > <NUMUER2> 

The H command will calculate the sum NUMUERl + NUMBER2 
and the difference NUMUERl - NUMBER2 and display the results on 
the next line of the screen as two hex words. The sum is the 
first word displayed, the difference is the second. 
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7.9 I - Display Disk Directory 


I 

The I command will display the directory of the 
diskette in drive one. The display can be suspended or halted 
with the SPACE or ESCAPE keys respectively. 

7.10 J - Create a Command File 


J Ifilespec, string 

The J command allows you to create command files for 
execution by the E command. The string in the command is any 
string of valid BUG/65 commands. The string will be written to 
the file specified by filespec in the format expected by the E 
command. Please note the comma after the filespec - it*s 
required, else BUG/65 won't know where your filespec stops and 
your command string starts. Also note that the J command 
doesn't allow multiple commands in the command line to be 
executed after the J command - everything in the line after the 
filespec and up to the RETURN is written to the file instead of 
being executed. 

7.11 K - Convert Hex to Decimal 


K <NUMQER> 

The K command will convert NUMBER to a decimal number 
and display the result on the next line of the screen. NUMBER 
can be any valid address expression. 

To convert decimal to hex, just display memory at the 
decimal location of the number you want to convert. The hex 
equivalent of the decLinal location appears in the display output 
as the hex word on the beginning of the line. For example, to 
convert 1000 decimal to hex, just execute the command M D .1000". 
You'll see the hex conversion of 1000 as the first hex word on 
the next line. 
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7.12 
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L - Locate a Hex String 


• » • ■ ••••*► 

L <START> <END> <BYTE1> <BYTE2> ... <BYTEn> 


The L command . will search the block of memory 
beginning at START and ending at END for a hex string. The 
hex string is defined by BYTE1...BYTEn, which are 
interpreted as the hex bytes of the pattern string. (On y 
the least significant bytes of the address values are used 
for each byte in the string.) Wildcard bytes which will 
match any byte in memory may be specified by the character 
-»« the string. BUG/65 will output the addresses of 
every occurrence of the string found in the block. For 

examples: 

L 1000 lOfc'F 41 42 43 /* will locate any occur- 

/* rences of the string "ABC 

/* in the memory block 

/* $1000 to $ 1 0 F F 

L 1000 2000 10 * 20 /* will locate any occur- 

/* rences of a three—character 

/* string which begins with 

/* $10 and ends with $20 in 

/* the memory block $1000 

/• to $2000 

7.13 m - Move a Memory Block 


M < START > < END> <T0> 

The M command will move the block of memory 
beginning at START and ending at END to TO. BUG/65 will 
take care to handle overlapping moves correctly, either for 

moves up or down. 
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7.14 


P - Select Output Devices 


P [S] [P] 

The P command is used to select output to either 
the screen ("S") or the printer ("P") or to both ("SP"). 
For example: 

PS /* turns screen output on, printer output off 

p P /* turns printer output on, screen output off 

PSP /* turns both screen and printer output on 
p /* turns both outputs off - commands will 

/* still be accepted and executed, you just 
/* won't see their entry or output anywhere. 

In addition to allowing you to list BUG/65 results 
to the printer, this command was designed to allow you to 
debug the generation of intricate screen displays without 
having the outputs of BUG/65 commands scroll your displa 
off the screen. It is a little crude, and might have a fe 
problems depending on what your program has done to OS, but 
is handy to have in emergencies. (The *LFFLAG and NULFLG 
bytes in the Configuration Table can help you here - see 

section 11.) 

7.15 Quit to OS/A-*- command 


Q 

The Q command will coldstart DOS. The results are 
essentially the same as when you puwer-up the machine. 
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7.16 


Read Commands 


7.16.1 R - Read a File 


R [ <OFFSET> ] Ifilespec 

The R command is used to load binary files. If 
OFFSET is specified, then OFFSET is added to the load 
address(es) specified in the file, and the data will be 
loaded at the loading point*s) plus OFFSET. This allows you 
to load a file into a different memory location than where 
it is origined at. After the file is loaded, the load 
starting point specified in the file is placed into tie 

user's l*C register. 

BUG/65 supports concatenated binary file sections 
as described in the DOS 2.0S manual. If such a file is 
loaded using the OFFSET option, however, ALL file sections 
will be loaded starting at the load addresses specifie< in 
the file plus OFFSET. In addition, the user's PC register 
will contain the value of the load point of the last file 

section loaded (not plus OFFSET). 

7.16.2 R% - Read Sector(s) 


IU [ < SECNO > [ < BUFFER > [ <NOSECS> ] ] 3 

The R% command allows you to read a sector or a 
group of sectors from a diskette in disk drive number one. 
SECNO specifies the sector number to be read and defaults to 
one. BUFFER specifies the buffer the sector is to be read 
into and defaults to BUG/65's loadpoint plus $2H0d. NOSECS 
specifies the number of sectors to read and defaults to one. 
If more than one sector is specified, then consecutive 
sectors are read sequentially into memory beginning at 

BUFFER. 
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7.17 S - Change Memory, Numeric mode 


S <ADDR>)6 

The S command allows you to replace the contents 
of memory bytes beginning at location ADDR with numerical 
values. As soon as you type the required space character 
after the address, BUG/65 will prompt you with the current 
contents of the memory location at ADDR. Those contents 
will be displayed as a hexadecimal byte value. At that 
point, you have the following options: 

1. Typing SPACE will cause the current memory 
location to be skipped and the contents of the next memory 
location to be displayed. 

2. Typing an UNDERLINE will cause the current 
address to be decremented by one. The new address is then 
displayed on the next line of the screen followed by the 
contents of the new memory location. 

3. Typing a RETURN will cause the address of the 
current memory location to be displayed on the next 1ine of 
the screen followed by the contents of the current location. 

4. Typing ESC will get you out of the command and 
put you back into command entry mode. 

5. Typing an address value (any valid address 
expression) will cause that value to he entered into memory 
at the current', address. The address is then incremented by 
one and the contents of the new memory location are 
displayed. (only the least significant byte of the address 
value will be entered into memory.) 

After you exercise any option except option 4., 
BUG/65 will again prompt you with the contents of the 
current memory address anil you may select any of these 
options again. 
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7.18 T - Trace a User Program 


T [S] [ <COUNT > ] 

The T command will single-step through user 
program instructions beginning with the instruction at the 
current user PC register. The number of instructions to be 
executed are specified by COUNT, which defaults to one. If 
“S" is specified, then all of the instructions in a 
subroutine are counted as one instruction for tracing 
purposes — the trace is turned off until return from the 
subroutine ( M S" stands for "skip the subroutine"). After 
every instruction traced, BUG/65 will display the contents 
of the user's registers. Some examples: 

T /• will execute one instruction and then 

/• display the register contents 

T 5 . /* will execute five instructions, .lisplaying 

/* registers after each instruction 

TS lfc) /• will execute 16 instructions. If any of 

/* the instructions are JSR's, then the 
/* trace will be turned off after the JSR 
/* until the subroutine executes an RTS 

The trace command can't be use to trace 
instruction execution through PROM resident code. Any 
attempt to do so, or to trace through non-existent memory, 
will result in a "BREAKPOINT ERROR". 

7.19 U - Call a User Subroutine 


U <ADDR> [ < PARAM > ] 

The U command is used to call a user subroutine at 
ADDR. The user routine is passed the optional parameter 
PARAM in the X register (low byte) and Y register (high 
byte). The user routine should return to BUG/65 via an RTS 
instruction. If PARAM isn't specified, then zero is used. 
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7.20 V - Display User's Registers 


V 

The V command will display the contents of the 
user's registers in the following format: 

A X Y SP NV_BDIZC PC INSTR 
tin nil till HH BBDBBBBB UHHU LDA 1000, X 

This is interpreted as follows: 

A ■ the hex value of the A reg 

X * the hex value of the X reg 

V » the hex value of the Y reg 

SP - the hex value of the stackpointer 

N * the binary value of the negative flag 

V =* the binary' value of the overflow flag 

=* the binary value of an unused bit in the 

“ status reg 

B * the binary value of the break flag 

D * the binary value of the decimal flag 

I » the binary value of the interrupt enable bit 

Z = the binary value of the zero flag 

C * the binary value of the carry flag 

PC * the hex value of the PC reg (This is a 

pseudo register maintained by BUG/65. 

It contains the location of the next 
user program instruction to be executed.) 

INSTR * the instruction at the current PC 
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7.21 Write Commands 


7.21.1 W - Write a File 


W [ :A ] <START> <END> Ifilespec 

The W command is used to write a binary file. 
Memory from START to END is written to the file specified by 
filespec in the standard OS/A+ binary file format. If the 
**; A" option isn't specified, then the data written will 
replace the current contents of the file if the file already 
exists. If the M :A" option is specified, then the data is 
appended to any data already in the file. A load header 
consisting of a start and end address as described in the 
OS/A-*- manual will precede the appended data. 

7.21.2 W% - Write Sector(s) 


W% C <SECNO> [ < DUFFER> [ <NOSECS> ] ] ] 

The W% command is used to write a sector or a 
group of sectors to a diskette. SECNO specifies the sector 
number to be written and defaults to one. DUFFER specifies 
the memory location of the sector data to be written and 
defaults to the DUG/t>5 loadpoint plus $20(JU. NOSECS 
specifies the number of sectors to be written and defaults 
to one. If more than one sector is specified, then 
consecutive sectors are written sequentially from memory 
beginning at DUFFER. 


» 
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7.22 X - Change User's Registers 


X REGNAME 

The X command allows you to change the contents of 
user registers. REGNAME is a one-character register name 
mnemonic. The allowed register names and their meanings 
are: 

A = A register 

X = X register 

Y =* Y register 

S = stackpointer register 

P =* program counter pseudo-register 

F ■ status register (flags) 

After you type in the name of the register to be 
changed, BUG/65 will prompt you with that name character 
followed by an equals sign. At that point you have the 
following options: 

1. Enter the new value for the register. The new 
value may be any valid address expression. After the new 
value, typing RETURN will end the command. Or you can type 
SPACE which will prompt you with another register name for 
possible change. The next register name is determined by 
the order of the above list. For example, if you change 
register Y then hit a space after the new value, BUG/65 will 
prompt you for possible change of register S. This prompt 
list continues through register F and then wraps back to 
register A again. 

2. Enter RETURN or ESC to end the command. 

BUG/65 will display the new contents of the registers and 
then put you back into command mode. 1 
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7.23 Y - Disassemble Memory Block 


Y < START > <END> 

The Y command will disassemble instructions in 

memory beginning at START and ending at END. The tallowing 

conventions are used in the disassembly: 

1. Standard MOS Technology mnemonics are used for opcodes. 

2. Illegal opcodes are displayed as ” * * * " • 

3. All numeric operands are displayed as hexadecimal 
numbers. 

4. Zero page operands will display as two hex digits, all 
other non-iinmed i a t e operands will display as four hex 
digits. 

5. No operand is displayed for accumulator mode operands. 







7.24 Z - Instant Assembler 


Z <ADDR># 

The Z command allows you to assemble instructions 
to be stored in memory at ADDR. Immediately after typing 
the SPACE character (or RETURN, which is allowed as well), 
BUG/65 will prompt you with the current program counter 
value of the instant assembler (which initially will be 
ADDR). At that point you may type in a valid assembly 
language instruction. The format for an instruction line 
is: 

[<LABEL>] <OPCODE> [<OPERAND>] 

LABEL may be any label in the form "Ln“, where * , n H 
may be any digit from zero to nine. OPCODE may be any valid 
MOS Technology instruction mnemonic or one of two pseudo-ops 
(described below). OPERAND, if allowed by the addressing 
mode of the instruction, may be any valid address 
expression. At least one space must separate a label from 
an opcode or an opcode from an operand. 

After typing your instruction, type RETURN and the 
instruction will be entered into memory at the current PC if 
it doesn’t contain any errors. If there are any errors, 
then BUG/65 will display an error message and will reprompt 
you with the current (unchanged) PC. If there are no 
errors, then BUG/65 will display the object code created by 
the instruction to the right of the instruction on the 
screen and will prompt you with the PC of the next 
instruction on the next screen line. You may exit the 
instant assembler by typing ESC at any time, or by typing 
RETURN by itself m response to the PC address prompt. 

The instant assembler provides you with two 
pseudo-ops. “/" followed by an address will change the PC 
to that address. It acts like an ORG ("•*") paeudo-op. For 
example, ’*/4O0O" will set the PC of the next instruction 
location to $4000. followed by an address will insert 
the value of that address (least significant byte) at the 
current PC and bump the PC by one. It acts like a DB 
(.BYTE) pseudo-op. For example, **>34** will insert the hex 
byte 34 at the current PC. 
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Special Command Modifiers 


The instant assembler provides a simple labeling 
capability. You may prefix an instruction with a two 
character label of the form "Ln*', where “n" may be any digit 
from 0-9. You may then use that label as an operand in an 
instruction, with the following three restrictions! 

1. ) Immediate type operands (£HH) can't be labels. 

2. ) Indirect type operands can't be labels. 

3. ) A label can’t be combined with any of the standard 
address operators (♦, X, etc.) 

Label references may be forward or backward. 
BUG/65 will store unresolved references and resolve them 

when the label is later defined. You may reference 

undefined labels twenty times before BUG/65 runs out of room 
to store the unresolved locations - you'll then get an error 
message and the assembly will be aborted. The same label 
may be reused more than once. In such cases, BUG/65 will 
use the last defined address of the label when it is 
referenced. 

If any labels have been referenced but not defined 
when you exit the instant assembler, BUG/65 will prompt you 
with a message and the label name followed by an equals 
sign. At that point you may either define the label by 

entering any valid address expression followed by a RETURN, 
or you may chose not to define it and simply hit RETURN. If 
you don't define the label, then the value of the label is 

defaulted according to the following two rules. 

1. ) If an instruction using the undefined label is a 
relative branch, then the value of the label for 
that instruction defaults to the location of the 
instruction plus two. 

2. ) For all other instructions, the value of the libel 
defaults to the location of the instruction plus 
three. 


These rules guarantee that all branching 
instructions using undefined labels are effectively turned 
into NOP'S. This offers some measure of protection against 
a program going into never-never land. (If you reference a 
label that isn't yet defined, the object code displayed to 
the right of the instruction on the screen will show 
addresses generated according to these rules. Don't worry, 
when the label is subsequently defined, BUG/o5 goes back and 
fixes up all these references.) 







SECTION fi i 


8.1 Repeat Last Command Line 
(RETURN) 


The last command line entered and executed may be 
repeated without typing the whole thing in again — just hit 
RETURN. BUG/65 remembers the last line entered for just 

this purpose. 

8.2 Repeat Command Line Forever 


/ 

Appending a slash to the end of a command line 
will cause BUG/65 to repeat the execution of that command 
line forever. The only way to stop such a repeat is to 
suspend or abort the command. 

* 

8.3 Display Last Command Line 



If you want to see what your .last command line 
was, possibly because you might want to repeat it, just type 
the ’*=»" character as the first character of the new command 
line. BUG/65 will display the last line entered for you. 


S 
















SECTION 91 


QUG/65 Memory Protection 


SECTION 10: 


BUG/65 Memory Usage 


BUG/65 won't allow you to modify any portion of 
it's code or variable storage areas with a BUG/65 command. 
Any attempt to do so will result in a "PROTECTION ERROR". 
For example, if we assume that the BUG/65 was loaded via the 
command "BUG65 2000", the following command wllL cause an 
ef ror because it attempts to move a memory block into 
BUG/65 * s area; 

M 40J0 40FF 2000 

UUG/65 protects all memory from loadpoint to 
1oadpuint♦$lFFF in this manner, where loadpoint is that 
specified in the invoking OS/A* command line (or LOMEM, if 
no loadpoint is specified). (The memory protection feature 
can be turned off by changing a byte in the Configuration 
Tab 1 e . ) 









BUG/65 uses memory from $80 to $XX and loadpoint 
to loadpoint+$01FF for variable storage. You can determine 
the value of XX by looking at the LSTPG0 byte in the 
Configuration Table. It uses memory from loadpoint+$200 to 
Ioadpoint+$1FFF for code storage. 


10.1 Page Zero Sharing 


BUG/65 will share the page zero memory that it 
needs with a user program. It does this by keeping two 
copies of these page zero locations. When BUG/65 is 
running, the BUG/65 page zero locations contain BUG/65's 
stuff. When a Go is done to a user program, BUG/65 will 
save it's own page zero data and replace it with the user's 
data. If a user program breaks back to BUG/65, the reverse 
operation is performed. 

In addition, BUG/65 will translate any command 
reference to these shared page zero locations so that the 
user may modify or inspect his own page zero data. It does 
this by translating any command reference to the user's page 
zero data to the location where the user's copy of the data 
is actually being stored. This is all transparent to the 
user. For example, you can fill memory from $00 to $FF with 
zeros without crashing BUG/65. If you then display $80 to 
$FF, you will see zeros. They aren't really in locations 
$80 to $ FF of course, but they will be when you run your 
program. (This is the reason it may seem to take an 
extraordinarily long time to perform certain commands 
(Fi 1 JLs, _ . for oxample). The reason is that every memory 
reference has to go through this translation process — both 
to translate zero page references if necessary and to check 
to make sure that BUG/65 isn't being overwritten.) 









SECTION Hi Customization with the ConfiguratLon Table 


Thore is a Configuration Table located near the 
beginning of the code segment of BUG/65. By changing this 
ddta, you can customize some BUG/65 stuff. In the table 
which follows, "+$xxx* means that the configuration value is 
located $xxx bytes above the loadpoint address, where 
loadpoint is the address specified in the invoking OS/A + 
command line (or LOMEM, if loadpoint is not specified). 
Example* if the invoking command was "BUG65 6000*', then 
D1SPV will be located at 56209. 

NAME LOCATION FUNCTION/COMMENTS 

DISPV +5209 * A JMP “instruction to 3UG7 65' s display a 

character routine. All chars displayed 
on the screen go through here. The char 
to be displayed is passed in reg A. 

PRINTV +$20C A JMP instruction to BUG/65*s print a 

character routine. All chars sent to the 
printer go through here. The char to be 
printed is passed in reg A. 

GETKYV + $20F A JMP instruction to BUG/65's get a 

keyboard character routine. All keyboard 
reads go through here. The key read is 
returned in reg A. 

TSTKYV +5212 A JMP instruction to BUG/65*s test for a 

key waiting routine. All tests for key 
waiting go through here. If no key is 
waiting, the equal flag is returned set. 
(The key is NOT returned by this routine 
- GETKYV will be called to read the key 
if there's one waiting.) 

BEEPV +5215 A JMP instruction to BUG/65's bell 

routine. All beeps are generated through 
here. To eliminate the beeps, just patch 
this out with an RTS. 


CHRCLR 

+5218 

Character background color byte value. 


CHRLUM 

+ 5219 

Character luminance byte value. 


BRDCLR 

+ 5 2 l A 

Border color byte value. 


EOLBYT 

+$2 IB 

This is the byte sent to the printer 
the end of a line. Normally set to 
or 9BH. 

at 

0DH 
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+ 521C 


LFFLAG 


NULFLG 


+ 521D 


If nonzero, then a linefeed character is 
sent to the printer after every EOLBYT. 

If nonzero, then 40 nulls will be sent 
to the printer after every line. Used to 
flush the printer buffer maintained by the 
ATARI OS so that all lines will print 
immediately. 


PROTFG 


+5 2 IE 


If nonzero, then BUG/65 will not 
itself to be overwritten with a 
command. If zero, then BUG/65 will 
itself to be modified. 


allow 

BUG/65 

allow 


+521F 


MCBEND +521F High byte of end address of BUG/65*s 

code. Normally set to high byte address 
of 1oadpoint+52000 (e.g, $50 if the 
invoking 0S/A+ command were BUG65 3000). 
You would change this if you added any 
user command handlers after BUG/65. The 
handlers would then be included in 
BUG/65's memory protection features. 

To change anything in the Configuration Table, you 
must first disable memory protection by writing a small 
program to stuff a zero into PROTFG. For example, assuming 
that the loadpoint is $2000 (command line was BUG65 2000), 
then UBing the instant assembler, you could enter **LDA 10, 
STA 221E, RTS" at location $5000, and then run the program 
with the "U" command by entering M U5000 <RETURN>". This 
will disable memory protection. Then make your changes, 
reenable memory protection if you want by storing $FF into 
PROTFG, then dump the modified BUG/65 to diskette. 

Be careful when changing any of the JMP 
instruction vectors. Since BUG/65 is constantly calling 
these locations, the instant you change them control will be 
passed to the new routine. Your replacement routines had 
better be in place and ready to run or it's ga-ga time. 
Actually, you will probably have to change all three bytes 
of a vector at once with a small user program. 

Also, be careful about calLing the vectors DISPV, 
PRINTV, GETKYV, TSTKYV, and BEEPV. Since they use BUG/65's 
page zero data to operate, they can't be called from a 
running user program without first calling the MCBGP0 
routine defined in the User Program Interface section. 
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SECTION 12: User Command Interface 


It's possible to add commands to BUI/65. The 
hooks to do so have been provided in a <j roup of vectors 
located at loadpoint+$022O called the User Comman 1 Interface 
Vectors. These vectors provide most of the interfaces to 
BUG/65 that you'11 need to add commands. 

The commands you add may be activated by any non— 
BUG/65 command char. For example, you could add the numeric 
conunands “1" through M 9 M . When BUG/65 recognizes a non- 
alphebetic command character, it will call the vector 
U5EKCMD. In it's initial state, USHCMD is just a 3-byte 
subroutine that returns the equal flag reset. BUG/65 
assumes that the equal flag being reset means that a user 
command handler considers the command illegal. In this 
case, BUG/65 will report a "CMD ERROR". If USRCMD returns 
the equal flag set, then BUG/65 assumes that a user command 
handler processed the command. In this case, BUG/65 won't 
generate a command error, and will proceed to process the 
rest of the command line. 

So, to add your own command handler, just patch a 
JMP to your handler at USRCMD. BUC/b5 will pass you the 
command character that it considered illegal in reg A. On 
return, you must indicate the status of the command - equal 
set means you handled it, equal reset means you didn't like 
it either. 
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There are a number of other vectors in the User 

Interface group which you may use to process the command. 

Here's the complete list (and, as in the previous section, 

the string "+$xxx" indicates a displacement from the 

loadpoint): 

NAME LOCATION FUNCTION/COMMENTS 

USRCMD + $220 Subroutine called by BUG/65 on every non 

alpha comand char. Returns equal set if 
command handled by user# else equal 
reset. 

GETCIIR +$223 User handler can call this to get the 

next char from the command line in reg 

A. 

PUTCHR +$226 User handler can call this to return the 

last char taken from the command line. 
The char itself doesn't have to be 
passed. This is used to put chars back 
that you've taken but don't want - like 
an EOL. 

GET 1HX +$229 User handler can call this to collect a 

hex address from the command line. The 
.address is returned in a word at 
$FE,$FF. If next command line chars are 
not a valid address, zero is returned. 

GET2UX +$22C User handler can call this to collect 

two hex addresses from the command line. 
The first address is returned in a word 
at $FC,$Fb, the second at $FE,$FF. Zero 
is returned for any invalid address. 

GET3IIX *$22F User handler can call this to collect 

three hex addresses from the command 
line. The first address is returned in a 
word at $FA,$FB, the second at $FC,$FD, 
and the third at $FE,$FF. Zero is 
returned for any invalid address. 
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